home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / tex / cc21d.zip / CC.DOC < prev    next >
Text File  |  1994-03-08  |  9KB  |  222 lines
  1.  
  2.  
  3.                                   CC, v2.1
  4.                                 -------------
  5.                                 from TifaWARE
  6.  
  7.  
  8.  
  9.  
  10. What's New
  11. ----------
  12.  
  13.      Although CC is a pretty simple program, earlier versions do appear to
  14. suffer from one problem. When used to redirect output to a HP LaserJet
  15. printer CC sometimes appears to lose formfeed characters. Actually, this
  16. is not a problem with CC but occurs because the printer ignores formfeeds
  17. found anywhere other than at the start of a line. To avoid this aberrant
  18. behaviour then, formfeeds are now preceded by a single carriage return
  19. starting with version 2.1.
  20.  
  21.      Many of the principal functions in CC have been completely rewritten
  22. for version 2.0. Additionally, AT&T's getopt() function is now used for a
  23. consistent method of processing commandline options. Since it did not get
  24. much use, the tab-expansion option will no longer be included in CC.
  25.  
  26.      Version 1.2 of CC does not represent much of an improvement over the
  27. preceding version, at least from the user's viewpoint. Some of the code
  28. for displaying the on-line help message was improved, and error messages
  29. are formated in a slightly different fashion. 
  30.  
  31.  
  32.  
  33.  
  34. Introduction
  35. ------------
  36.  
  37.  
  38.      In my work on an IBM mainframe, I frequently come across files with
  39. carriage controls in the first column of each line. Printing such files on
  40. the mainframe's printer is no problem, but more often than not I'd rather
  41. download them to my PC and print them at my convenience. The problem,
  42. though, has been that PC printers don't understand carriage controls, just
  43. characters like <form feed>, <carriage return>, <linefeed>, etc, ... 
  44.  
  45.      The algorithm to replace those carriage controls with characters PCs
  46. understand is simple enough. Yet calling up an editor and making the
  47. changes for each file is a hassle I'd rather avoid. Hence I've devised
  48. this little text filter. It's called, appropriately enough, CC. And its
  49. sole purpose is to process files with carriage controls.
  50.  
  51.      Characters are read one at a time from the input file(s). Most are
  52. simply output with no changes; however, the first character in each line is
  53. interpreted as an ASA carriage control in the following fashion:
  54.  
  55.      Carriage Control    Interpretation
  56.      ----------------    --------------
  57.      space               Advance 1 line before printing
  58.      0                   Advance 2 lines before printing
  59.      -                   Advance 3 lines before printing
  60.      +                   Surpress line advance before printing
  61.      1                   Advance to new page
  62.  
  63. With one exception, invalid carriage controls cause CC to print a <carriage
  64. return>, the rest of the line, and then a <linefeed>. [The sole exception
  65. concerns empty lines, which are treated the same as lines composed of just
  66. one space.] Should you ever see a bunch of lines missing letters at the
  67. start, you probably filtered a file through CC which didn't contain
  68. carriage controls. 
  69.  
  70.  
  71.  
  72.  
  73. Usage
  74. -----
  75.  
  76.  
  77.      Running this program is quite simple. Assuming you've placed CC.COM
  78. on your system where DOS can find it, type CC -? to display a brief help
  79. message similar to the following:
  80.  
  81.      TifaWARE CC, v2.1d, processes ASA carriage control characters.
  82.      Copyright (c) 1991-1993 by TifaWARE/George A. Theall.
  83.      
  84.      usage:  cc [options] [file(s)]
  85.      
  86.      Options:
  87.        -? = provide this help message
  88.      
  89.      Stdin is used if no files are specified. Wildcards are not allowed.
  90.  
  91. [If you don't remember anything else from reading the documentation, at
  92. least remember how to display this help message.] Files names must be
  93. unique; that is, wildcards are _not_ supported. 
  94.  
  95.      CC sequentially processes each file named on the command line, or
  96. standard input if none are specified. Trouble opening a file (because
  97. say, the name was misspelled) simply causes CC to skip to the next file. 
  98. A read or write error during processing will, however, cause the program
  99. to abort. 
  100.  
  101.      CC's output is written to a device called stdout, which is normally
  102. your computer's screen. Using the DOS redirection characters '>' and '|',
  103. you could send this output to a disk file, printer, or even use it as input
  104. into another program. [Refer to your DOS manual for more information on
  105. output redirection.] The flexibility of this approach should be clear. 
  106.  
  107.  
  108.  
  109.  
  110. If You Have Any Trouble
  111. -----------------------
  112.  
  113.  
  114.      CC will attempt to let you know of any problems that arise. Here are
  115. the messages you might see and how you should deal with them:
  116.  
  117.      cc: illegal option -- x.
  118.           - Type "CC -?" for a list of valid options. If your
  119.             file's name starts with a '-', you can avoid having
  120.             CC treat the name as a set of options by prefixing
  121.             the name with a path; e.g., CC .\-ODDNAME.LOG.
  122.  
  123.      cc: can't open BADFILE.
  124.           - CC was unable to open for input the file BADFILE.
  125.             Check the spelling and make sure the file actually 
  126.             exists.
  127.  
  128.      cc: can't read from SOMEFILE; processing halted at line 117.
  129.           - CC ran into trouble while attempting to read from
  130.             SOMEFILE. The line number reported by CC refers to
  131.             the last line processed from the *input* file. This
  132.             error indicates a serious problem exists with your
  133.             file. You should examine the file using a program
  134.             such as Norton Utilities or make another copy of
  135.             the file for CC to use.
  136.  
  137.      cc: can't write to stdout; processing halted at line 92 of SOMEFILE.
  138.           - The reason for this error depends on the particular type
  139.             of output redirection (if any) you're using. Perhaps the
  140.             disk to which you're sending output has become full;
  141.             perhaps the printer has become jammed or lost power, ...
  142.             however, you should never see this one if you're just
  143.             sending output to the screen. Once again, the line number
  144.             reported by CC refers to the input file.
  145.  
  146. These error messages are written to the standard error device. In this
  147. way, they won't disappear down a pipe or into a file should you try to
  148. redirect CC's output. 
  149.  
  150.      Additionally, CC uses a return code to convey information about the
  151. success or failure of its operation. Possible return values are:
  152.  
  153.      Code      Meaning
  154.      ----      -------
  155.      0         All files were processed successfully
  156.      1         Help message was displayed
  157.      10        At least 1 file was not opened for processing
  158.      15        Trouble was encountered reading from a file
  159.      20        Trouble was encountered writing to stdout
  160.  
  161. You can test for these codes using the ERRORLEVEL variable in a batch file. 
  162.  
  163.  
  164.  
  165.  
  166. Requirements
  167. ------------
  168.  
  169.  
  170.      TifaWARE CC runs on machines operating under MS-DOS v2.xx or later,
  171. and requires about 10K of memory. It does not use BIOS calls, make direct
  172. writes to video RAM, or otherwise require machines to be "PC-compatible". 
  173. In fact, CC even runs properly on a DEC Rainbow!
  174.  
  175.  
  176.  
  177.  
  178. Who Owns It?
  179. ---------------
  180.  
  181.  
  182.      The source code for CC is public domain. I do, however, retain the
  183. copyright on the compiled program in order to abide by the license
  184. agreement for Borland C++; you may freely redistribute and use it.
  185.  
  186.      CC carries no obligation on my part to support users or provide
  187. future upgrades. I have tried to write clean code and believe it to be
  188. "bug-free". Nevertheless, you must use this program ***AT YOUR OWN
  189. RISK***.
  190.  
  191.      As author of CC, I ask of you two things: First, if you redistribute
  192. this program please keep together my original source code, documentation,
  193. and executable. This just makes it easier for others to use the software.
  194. Second, let me hear what you think of CC - I'd appreciate a postcard with
  195. your comments. Enjoy!
  196.  
  197.  
  198.  
  199.  
  200. Kudos
  201. -----
  202.  
  203.  
  204.      Borland deserves a great deal of credit for its compiler and stand-
  205. alone debugger. Together these products make C programming a joy. 
  206.  
  207.  
  208.  
  209.  
  210.  
  211.                           George A. Theall
  212.  
  213.